<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Chapter 4. Using DB_CONFIG to configure the Berkeley DB SQL interface</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Getting Started with the Oracle Berkeley DB SQL APIs" />
    <link rel="up" href="index.html" title="Getting Started with the Oracle Berkeley DB SQL APIs" />
    <link rel="prev" href="control_log_file.html" title="Controlling the Number of Accumulated Log Files" />
    <link rel="next" href="using_dbconfig.html" title="The DB_CONFIG File" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Chapter 4. Using DB_CONFIG to configure the Berkeley DB SQL interface</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="control_log_file.html">Prev</a> </td>
          <th width="60%" align="center"> </th>
          <td width="20%" align="right"> <a accesskey="n" href="using_dbconfig.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="chapter" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title"><a id="sql_db_config"></a>Chapter 4. Using DB_CONFIG to configure the Berkeley DB SQL interface</h2>
          </div>
        </div>
      </div>
      <div class="toc">
        <p>
          <b>Table of Contents</b>
        </p>
        <dl>
          <dt>
            <span class="sect1">
              <a href="sql_db_config.html#env-overview">Introduction to Environments</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="using_dbconfig.html">The DB_CONFIG File</a>
            </span>
          </dt>
          <dd>
            <dl>
              <dt>
                <span class="sect2">
                  <a href="using_dbconfig.html#dbconfigcreate">Creating the DB_CONFIG File Before Creating the Database</a>
                </span>
              </dt>
              <dt>
                <span class="sect2">
                  <a href="using_dbconfig.html#envrecreate">Re-creating the Environment</a>
                </span>
              </dt>
            </dl>
          </dd>
          <dt>
            <span class="sect1">
              <a href="configcache.html">Configuring the In-Memory Cache</a>
            </span>
          </dt>
        </dl>
      </div>
      <p>
            In almost all cases, there is no need for you to directly
            configure Berkeley DB resources; instead, you can use the
            same configuration techniques that you always use for SQLite,
            or use the Berkeley DB PRAGMAs describe  
            <a class="xref" href="dbsqlbasics.html" title="Chapter 1. Berkeley DB SQL: The Absolute Basics">Berkeley DB SQL: The Absolute Basics</a>,
            and
            <a class="xref" href="reppragma.html" title="Replication PRAGMAs">Replication PRAGMAs</a>.
            The Berkeley DB SQL interface will take care of the rest.
        </p>
      <p>
            However, there are a few configuration activities that some
            unusually large or busy installations might need to make and for
            which there is no SQLite equivalent. This chapter describes
            those activities.
        </p>
      <div class="sect1" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title" style="clear: both"><a id="env-overview"></a>Introduction to Environments</h2>
            </div>
          </div>
        </div>
        <p>
              Before continuing with this section, it is necessary
              for you to have a high-level understanding of Berkeley DB's
              environments.
          </p>
        <p>
              In order to manage its resources (data, shared cache, locks,
              and transaction logs), Berkeley DB often uses a directory
              that is called the <span class="emphasis"><em>Berkeley DB environment</em></span>.
              As used with the BDB SQL interface, environments contain log files and the
              information required to implement a shared cache and
              fine-grained locking. This environment is placed in a
              directory that appears on the surface to be a SQLite
              rollback file.
          </p>
        <p>
              That is, if you use BDB SQL interface to create a database called
              <code class="literal">mydb.db</code>, then a directory is created
              alongside of it called <code class="literal">mydb.db-journal</code>.
              Normally, SQLite creates a journal file only when a
              transaction is underway, and deletes this file once the
              transaction is committed or rolled back. However, that is not
              what is happening here. The BDB SQL interface journal directory contains
              important Berkeley DB environment information that is meant to
              persist between transactions and even between process
              runtimes. So it is very important that you do
              <span class="emphasis"><em>not</em></span> delete the contents of your Berkeley DB
              journal directory. Doing so will cause improper operation and
              could lead to data loss.
          </p>
        <p>
              Note that the environment directory is also where you put
              your <code class="literal">DB_CONFIG</code> file. This file can be used to
              configure additional tuning parameters of Berkeley DB, if its
              default behavior is not appropriate for your
              application. For more information
              on the <code class="literal">DB_CONFIG</code> file, see
              the next section.
          </p>
        <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
          <h3 class="title">Note</h3>
          <p>
                  Experienced users of Berkeley DB should be aware
                  that neither <code class="literal">DB_USE_ENVIRON</code> nor
                  <code class="literal">DB_USE_ENVIRON_ROOT</code> are
                  specified to
                  <code class="methodname">DB_ENV-&gt;open()</code>. As
                  a result, the <code class="literal">DB_HOME</code>
                  environment variable is ignored. This means that the
                  BDB SQL interface will always create a database
                  in the location defined by the database name given to
                  the BDB SQL interface.
              </p>
        </div>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="control_log_file.html">Prev</a> </td>
          <td width="20%" align="center"> </td>
          <td width="40%" align="right"> <a accesskey="n" href="using_dbconfig.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Controlling the Number of Accumulated Log Files </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> The DB_CONFIG File</td>
        </tr>
      </table>
    </div>
  </body>
</html>
